Skip to content

Improve getting started experience #16065

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 9 commits into
base: master
Choose a base branch
from
Draft

Improve getting started experience #16065

wants to merge 9 commits into from

Conversation

asafashirov
Copy link
Contributor

No description provided.

@claude Claude
Copy link
Contributor

claude bot commented Sep 23, 2025

Review Summary

This PR adds a new getting started experience across 4 cloud providers. The content is well-structured and comprehensive, but there are several issues that need to be addressed before merging.

Issues Found

Critical Issues

Missing newlines at end of files (Lines: EOF)
All 5 new files are missing the required newline at the end:

  • content/start-now-1/_index.md:23
  • content/start-now-1/aws/_index.md:305
  • content/start-now-1/azure/_index.md:341
  • content/start-now-1/gcp/_index.md:310
  • content/start-now-1/kubernetes/_index.md:498

This violates the absolute prohibition in AGENTS.md: "New files: Must always end with a newline."

Style Guide Violations

Heading capitalization issues

  • content/start-now-1/aws/_index.md:295: "What's Next?" should be "What's next?" (H2+ should be sentence case per STYLE-GUIDE.md:29)
  • content/start-now-1/azure/_index.md:326: Same issue
  • content/start-now-1/gcp/_index.md:295: Same issue
  • content/start-now-1/kubernetes/_index.md:485: Same issue

Semantic line break violations
Multiple instances where sentences are not properly broken across lines (STYLE-GUIDE.md:65):

  • Long sentences in meta descriptions should be broken
  • Several paragraph sentences should start new lines

Content Issues

Language consistency

  • content/start-now-1/aws/_index.md:16: "Get started with Pulumi Cloud" - should use consistent capitalization
  • Several instances of informal language like "Get started" vs "Get Started" need consistency

Link verification needed
The following external links should be verified:

  • https://app.pulumi.com/signup (appears in all files)
  • https://slack.pulumi.com (appears in all files)
  • GitHub example links need verification

Technical Accuracy

Code examples
The code examples appear technically sound, but should be tested to ensure they work as documented. The examples follow established patterns from the existing documentation.

Command sequences
Installation and configuration commands look correct, but recommend testing across all supported platforms.

Positive Aspects

  • Comprehensive coverage across major cloud providers
  • Consistent structure and formatting across all files
  • Good use of Hugo shortcodes and choosers
  • Clear step-by-step progression
  • Helpful "What's next?" sections with relevant links

Recommendations

  1. Immediate fixes required:

    • Add newlines to end of all files
    • Fix heading capitalization (H2+ to sentence case)
    • Apply semantic line breaks throughout

  2. Before merging:

    • Test all code examples to ensure they work
    • Verify all external links resolve correctly
    • Consider testing installation commands across platforms

  3. Style improvements:

    • Standardize "Get started" vs "Get Started" usage
    • Review for consistent Pulumi product name usage

The content quality is high and the structure is excellent. Once the style guide violations are addressed, this will be a valuable addition to the getting started experience.

@pulumi-bot
Copy link
Collaborator

Your site preview for commit 71ad0f9e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16065-71ad0f9e.s3-website.us-west-2.amazonaws.com.

@pulumi-bot
Copy link
Collaborator

Your site preview for commit f39fc5f is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16065-f39fc5fc.s3-website.us-west-2.amazonaws.com.

@meagancojocar
Copy link
Collaborator

Asaf mind adding a PR description explaining what change we are making? Is Joe the only reviewer we want?

@asafashirov
Copy link
Contributor Author

Asaf mind adding a PR description explaining what change we are making? Is Joe the only reviewer we want?

Sorry I meant to open the PR in Draft; discussion in Slack: https://pulumi.slack.com/archives/C07PNRRBR9P/p1758652504107689

I'll update with description once we agree on one of the three flows to test.

@asafashirov asafashirov marked this pull request as draft September 29, 2025 16:37
@asafashirov
Implement team feedback for start-now pages
06650c7 
- Remove text duplication in cloud selection grids (logos only)
- Add Oracle Cloud Infrastructure (OCI) support to all three flows
- Add Pulumi Cloud viewing encouragement as first item in all Next Steps sections
@pulumi-bot
Copy link
Collaborator

Your site preview for commit 4e51eb6 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16065-4e51eb6e.s3-website.us-west-2.amazonaws.com.

@asafashirov
Align OCI flows with other cloud providers
c51972d 
- Fix metadata format: change from cloud object to simple cloud_name field
- Add Pulumi Cloud sign-up as first step in all three flows
- Fix subtitles for consistency with other clouds
- Restructure start-now-1 with Quick Setup wrapper and numbered sections
- Restructure start-now-2 with proper numbered subsections
- Add missing no_on_this_page metadata field
@pulumi-bot
Copy link
Collaborator

Your site preview for commit c51972d is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16065-c51972d3.s3-website.us-west-2.amazonaws.com.

@asafashirov
Fix style guide violations from review feedback
135be52 
- Change all "What's Next?" to "What's next?" (sentence case for H2+ headings)
- Change all "Next Steps" to "Next steps" (sentence case)
- Standardize OCI titles from "&" to "and" for consistency with other clouds
- Align with style guide requirement that H2+ headings use sentence case
@pulumi-bot
Copy link
Collaborator

Your site preview for commit 135be52 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16065-135be526.s3-website.us-west-2.amazonaws.com.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@joeduffy joeduffy Awaiting requested review from joeduffy

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@asafashirov @pulumi-bot @meagancojocar